Why use branches?

Developers often refer to the trunk and branches of a code base. What are they talking about? "Trunk" refers to the central source code that is used for continuous and ongoing development. Branches are forks in the code, which begin as identical to the trunk but are then used to apply major changes to the code while preserving the integrity of the code in the trunk.

Small modifications and enhancements are frequently made to almost every application, and these can be done in the main "trunk" of the code. However there are times when a major addition or change needs to be made and tested, or when competing modifications to the application are being tested. While the new functionality is being worked on, the current version needs to be maintained and updates applied as needed.

Alternatively, some teams work in exactly the opposite way: Major changes are made in the trunk, and as the trunk becomes stable, a copy is forked off into a branch to be tested as a release.

This is the kind of situation that calls for a branch. The new version is checked out into a "branch", and the main version (the "trunk") is worked on incrementally, as usual.

Jump down to chapter list

Note: This tutorial is based on Paul Glezen's wonderful branching article on the Eclipse site: Branching with Eclipse and CVS, used with his permission and under the terms of the EPL license. My aim in building onPaul's tutorial is to make it more accessible for beginners.

Sections:

Part 1: Creating the project.

Download this zip archive:
brtest.zip This files contained in this archive refer to two people who will be the "actors" in this tutorial, Paul and Wing. Decide who will be Paul and who will be Wing. If you are the only person who will be participating, then you will have to be both. Additional people can be additional "Wings." Whatever you do, use naming conventions and edit the content of the four text files in the archive to make them consistent with your chosen names, to avoid confusion.
Create a new workspace in a new, empty folder. Launch Eclipse. It asks you to select a workspace. Click Browse...
Choose a location and create a new folder.
Select the folder you created and click "Choose".
The browse dialog closes. Click the OK button.
You should see the Welcome screen. Click Open Workbench.
This would be a good time to set up your perspectives. If you aren't sure how to do this, Click here, then return back to this tutorial when you are done.
Select the "Resource" Perspective.
Create a new simple project by right-clicking inside the left column.
Choose General>Project
Call it [yourname]_Project and click OK. eg. john_Project, ellen_Project etc.
Right click on your project folder, and select Import.
Select General > Archive File
Click Browse... then navigate to brtest.zip. The "Into folder" setting should already be set to your project folder. Click Finish.
You will be returned to the main window. If you open the project folder, you should now see some files there.

Sharing the project
1. Now that you have a project, you need to check it into the repository. Right click the project folder and select Team>Share Project
2. Enter the repository information: Repository Login information for use with Eclipse: Server: cvss1d.mcit.med.umich.edu Repository name: mlearning pserver port: 2424 Repository location: /cvsrepositories/mlearning
3. Leave it set to "Use project name as module name". Click Next.
4. It will ask you to review and commit the new resources.
5. Right click the project folder and select Commit.
6. Add a comment to the comment area and click Finish.
7. It will confirm that the resources are in sync. Click Finish again. The name of the repository will now appear after the project folder name.
Creating a Branch

Any users who did not create the project should check it out from CVS now. If you don't know how to check out a project from CVS, View this tutorial then return here
1. Right Click the project folder and select Team>Branch
2. Call the branch "yourname_paulWorking," to indicate that you are Paul when you created this branch. Make sure "start working in the branch" is checked and click OK. We are adding your name to the branch title so that if several people are doing this part of the tutorial, the branch names will be distinct.
3. If you forget to click start working in the branch, right-click the project folder again, and select "Switch to another branch or version."
4. Select the desired branch and click Finish.
5. You can tell what branch you are in by looking at the name of the project folder. The branch name will be listed to the right of the project folder name.
Start editing in the branch as "Paul"
1. First we will be "Paul." Paul's is working in the branch "yourName_paulWorking".
  Open f1.txt in the text editor.
2. Show line numbers if necessary by right clicking in text editor, select Preferences..., and check Click show line numbers.
3. Change line 3 to read...
4. ..."This line changed by Paul in iter1. "
5. Note that the file now shows a ">" indicator showing that it is no longer synced with the repository.
6. Now open f1trivial.txt in the text editor.
7. Change line 3 to read "This line changed by Paul in iter1."
8. Commit all the changes by right-clicking the folder and selecting Team>Commit. Type a comment like "First iteration changes made by Paul." The version numbers will be 4 digit numbers: the 2 represents the branch number.
9. A best practice is to tag your milestones. Since this is Paul's first round of changes in this branch he will use the tag P1. Right click the project folder and select Team>Tag as Version. Type P1 and click OK.
Wing opens and edits the main trunk
Wing should now create her own workspace and import the HEAD of the project Paul created to it. If she already created her own workspace and acted as "Paul" to create a project branch, she can import Paul's project-trunk right alongside it.
1. Right click in the white area in the project explorer, and select Import
2. Select CVS >Projects from CVS.
3. Select the CVS repository you want to use from the list.
4. You may or may not have to sign in, depending on what you have already done.
5. Select the project you want to import. Click Next, NOT "Finish."
6. Add the word Trunk on to the end of the name so you can distinguish it from project branches of the same name.
7. Select HEAD from the list of tags. Click Finish.
8. You should now see a new Trunk folder in your Project Explorer. There will be no branch listed to the right of the folder name, indicating that you are NOT working in a branch with respect to this project.
9. Open f2.txt.
10. Change line 3 to read "This line changed by Wing in iter1." Save the change.
11. Open f3trivial.txt
12. Change line 9 to "This line change by Wing in iter1." Save the change.
13. Open f4.txt. Change line 3 to "This line changed by Wing in iter1." Save the file.
14. Commit all these changes and add a comment: "First iteration changes by Wing." The version numbers will remain 2 digit numbers because the changes were made on the trunk.
15. Best practice: Tag milestones. to come.
  Wing opens and edits the main trunk
  Wing should now create her own workspace and import the HEAD of the project Paul created to it. If she already created her own workspace and acted as "Paul" to create a project branch, she can import Paul's project-trunk right alongside it.
  1. Right click in the white area in the project explorer, and select Import
  2. Select CVS >Projects from CVS.
  3. Select the CVS repository you want to use from the list.
  4. You may or may not have to sign in, depending on what you have already done.
  5. Select the project you want to import. Click Next, NOT "Finish."
  6. Add the word Trunk on to the end of the name so you can distinguish it from project branches of the same name.
  7. Select HEAD from the list of tags. Click Finish.
  8. You should now see a new "Trunk" folder in your Project Explorer. There will be no branch listed to the right of the folder name, indicating that you are NOT working in a branch with respect to this project.
  9. Open f2.txt.
  10. Change line 3 to read "This line changed by Wing in iter1." Save the change.
  11. Open f3trivial.txt
  12. Change line 9 to "This line change by Wing in iter1." Save the change.
  13. Open f4.txt. Change line 3 to "This line changed by Wing in iter1." Save the file.
  14. Commit all these changes and add a comment: "First iteration changes by Wing." The version numbers will remain 2 digit numbers because the changes were made on the trunk.
  15. Best practice: Tag milestones. to come.
    
    Paul merges his changes back into the Trunk
    1. Put your "Paul" hat on. For purposes of this step, we are going to pretend that Wing's folder does not exist so we can practice switching to other branches. When last we left Paul, he was working in the branch "yourname_paulWorking." Expand the folder containing this branch. The changes Paul made in this folder have all been committed to CVS under the branch so they are completely backed up. So we can replace them with the Trunk version of the files and start merging Paul's changes back in to the Trunk.
    2. Right-click the folder and select Replace with Another Branch or Version...
    3. Select HEAD and click "OK."
    4. The branch name should no longer appear to the right of the project name.
    5. Right click on the project folder and select "Team>Merge...".
    6. Click Browse next to "Branch or version to be merged". Choose "yourname_paulWorking".
    7. It should fill in the common base version for you, starting with "Root_". Do not check "Merge non-conflicting changes and only preview conflicts." Click Finish.
    8. The view in Eclipse wil change to the Team Synchronize perspective,
    9. At this point I'd like to draw your attention to some handy buttons. Files that have NON-CONFLICTING incoming changes from the branch will display a little blue arrow. Files that have CONFLICTING incoming changes get a red double-headed arrow. If you forget what these symbols mean, you can mouseover the corresponand it will remind you that it means "Incoming Changes." Clicking the blue-arrow button will filter out all other types of changes, but you will still see the red-arrow files.. There is a red-arrow "Conflicts" button as well. Similarly, if you aren't sure what you are doing, you can mouse over the Synchronize button to see the name of the Merge and the name of the source of the changes.
    References

Why use branches?

Part 1: Creating the project.

Sharing the project

Creating a Branch

Start editing in the branch as "Paul"

Wing opens and edits the main trunk

Wing opens and edits the main trunk

Paul merges his changes back into the Trunk